package org.jpropelleralt.node;

import javax.swing.Icon;
import javax.swing.ImageIcon;

import org.jpropelleralt.path.PathStep;
import org.jpropelleralt.ref.Ref;

/**
 * A {@link Node} having an illustration {@link Ref}
 * with an {@link Icon} value.
 * The {@link Icon} MUST be immutable in order for the
 * {@link Ref} to function correctly -  {@link ImageIcon} 
 * and similar are good choices.
 * Often used with {@link Named} and {@link Described}
 * for {@link Node}s that will be displayed in a GUI.
 */
public interface Illustrated extends Node {
	
	/**
	 * Get the illustration for this {@link Node}
	 * Note that the {@link Ref} returned from this
	 * method must have the ref-name "illustration" in
	 * this {@link Node}.
	 * @return	{@link Node}'s illustration, as a {@link Ref}
	 */
	public Ref<Icon> illustration();
	
	/**
	 * The ref-name used within {@link Illustrated} nodes to
	 * refer to their illustration property.
	 */
	public final static String NAME = "illustration";
	
	/**
	 * {@link PathStep} from a {@link Illustrated} to its
	 * {@link Illustrated#illustration()} {@link Ref}.
	 */
	PathStep<Illustrated, Icon> toIllustration = new PathStep<Illustrated, Icon>() {
		public Ref<Icon> transform(Illustrated s) {
			return s.illustration();
		};
	};
}
